org.eclipse.jface.text.formatter
Interface IContentFormatterExtension2
- All Known Implementing Classes:
- ContentFormatter2
- public interface IContentFormatterExtension2
Extension interface for IContentFormatter
.
Updates the content formatter to be able to pass IFormattingContext
context objects to IFormattingStrategyExtension objects
operating in context based mode. The context based mode supersedes
the previous modes offered by IContentFormatter
, namely
partition aware/unaware formatting.
Clients using context based formatting call the method
format(IDocument, IFormattingContext)
with a properly
initialized formatting context.
The formatting context must be set up according to the desired formatting mode:
- For whole document formatting set the property
CONTEXT_DOCUMENT
. This is
equivalent to setting CONTEXT_REGION
with a region spanning the whole document.
- For single partition formatting set the property
CONTEXT_PARTITION
. The partition
property must correspond to a document partition in the current partitioning of the content formatter.
- For multiple region formatting set the property
CONTEXT_REGION
. Note that
the content formatter automatically aligns the region to a block selected region, and if the region spans
multiple partitions, it also completes eventual partitions only partially covered by the region.
Depending on the registered formatting strategies, more context information must
be passed in the formatting context, like e.g. CONTEXT_PREFERENCES
.
Note that in context based mode the content formatter is fully reentrant, but not
thread-safe. Formatting strategies are therefore allowed to recursively call the
method format(IDocument, IFormattingContext)
. The formatting
context is saved between calls to this method.
- Since:
- 3.0
- See Also:
IFormattingContext
,
FormattingContextProperties
format
public void format(IDocument document,
IFormattingContext context)
- Formats the given region of the specified document.
The formatter may safely assume that it is the only subject that
modifies the document at this point in time. This method is fully
reentrant. Formatting strategies registered with IContentFormatterExtension2
objects are therefore allowed to recursively call this method on
subregions of the region to be formatted.
The formatting process performed by format(IDocument, IFormattingContext)
happens as follows:
- In a first pass the content formatter formats the range of the
document to be formatted by using the master formatting strategy. This
happens regardless of the content type of the underlying partition.
- In the second pass, the range is formatted again, this time using
the registered slave formatting strategies. For each partition contained
in the range to be formatted, the content formatter determines its
content type and formats the partition with the correct formatting
strategy.
- Parameters:
document
- The document to be formattedcontext
- The formatting context to pass to the formatting strategies.
This argument must not be null
. Most
formatting strategies only require the CONTEXT_DOCUMENT
to be set. Depending on the registered formatting strategies,
more properties can be required.
Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.